Fritz: All Fritz/All Fritz.zip/All Fritz/FILES/PROGMISC/FPCDOCS.LZH/TOOLS.DOC

Text File | 1988-06-01 | 17KB | 455 lines

III.   PROGRAMMING TOOLS



1.   DUMP



The dump utility gives you a formatted hex dump with the ascii
text corresponding to the bytes on the right hand side of the
screen.   DUMP displays memory in the code segment, where code,
strings, and other data are stored.  XDUMP displays the list
segment, where colon definitions are stored.  YDUMP displays the
header segment.  These dump utilities are derived from the generic
dump function LDUMP, which displays a range of memory from a
memory segment whose segment address is stored in a variable
DUMPSEG.  DUMP, XDUMP, and YDUMP set DUMPSEG to the corresponding
segment and then do LDUMP.  One can store any segment address into
DUMPSEG and use LDUMP to display that part of the memory, the dump
segment, up to 64K bytes.

LDUMP does not change DUMPSEG but DUMP, XDUMP, and YDUMP do change
DUMPSEG to cs:, xs:, and ys:.  Their behavior takes a little bit
of getting use to, but they allow you to navigate through the
entire segmented memory space.

DUMPC@L fetches a byte in the segment specified by DUMPSEG.

DU displays 64 bytes in the dump segment and increment the memory
address by 64 so that you can continue dumping the next 64 bytes
with another DU.



2.   THE DEBUGGER



The debugger is very similar to the F83 debugger.  Some features
have been added to enhance its operation.  The decompiled source
for the current definition being debugged is displayed while
debugging. A typical command sequence might be as follows:

                DEBUG WORDS <enter>     specify WORDS to be debugged
                                        as soon as it is executed.
                        or

                DBG WORDS <enter>       debug WORDS right now.

Once in the debugger, you will be shown a display similar to the
following:

                17469   INWFLG          ?>  _

At this point, pressing return will cause the word INWFLG to be
executed, and the debugger will print the stack after execution,
and step to the next word in the list and wait for a command.
Notice the fields in the above example.  The number on the left is
the address in memory where the debugger is currently working.
The next word INWFLG is the word the debugger is about to execute.
The next symbol "?>" is a marker pointing to what will be the
printed stack contents after we press <enter>.  The question mark
symbol is the command we must press to see the command list for
the debugger.  If we press that now, we will see:

                C-cont, F-forth, Q-quit, N-nest, U-unnest:

These are the commands you can use in the debugger.  Their
functions are as follows:

        C-cont          Trace continuously until a key is pressed.

        F-forth         Allow entry of Forth command lines until
                        <enter> is pressed on an empty line.

        Q-quit          Quit the debugger, and unpatch next.

        N-nest          Nest into the ":" definition we were about
                        to execute.  Only works on ":" definitions,
                        and deferred words.

        U-unnest        Unnest the current ":" definition being
                        debugged.  Re-enters the debugger on the next
                        higher level.

You will have noticed that the upper portion of the screen is
filled with the source for the word you are currently debugging.
This is to make it easier to follow the debug process. You may
want to turn off the source display, if it interferes with your
the debuging process. The words to control this are:

                SRCOFF          turn off the source display
                SRCON           turn on the source display

The default state is ON.

DEBUG only sets the debugger up to debug a word.  The debugging
process does not start until the word is executed.  A new
debugging command DBG is added, which caused the following word to
be executed and debugged immediately.  The command sequence is:

               DBG <word_name> <enter>

It is much easier to use and makes much of the intricate behavior
of the F83 DEBUG transparent to the user.



3.   CONSTANTS AS VARIABLES


"Constants aren't; variables won't".

A set of operators has been included for manipulating constants.
Since constants are faster at run time than variables, performance
in critical operations can take advantage of these.  They may also
provide a somewhat more readable source.  Here is a list of them:

                =:              value =: constant-name
                                assign value to constant

                !>              value !> constant-name
                                assign value into constant-name

                @>              @> constant-name ( --- n1 )
                                returns contants of its BODY.

                +!>             value +!> constant-name
                                increment constant-name by value

                incr>           incr> constant-name
                                increment constant-name by one

                decr>           decr> constant-name
                                decrement constant-name by one

These operators are written in assembly, so they will be very
fast.



4.  HELP SEE WORDS' VIEW?



F-PC provides the standard F83 decompiler, called SEE.  SEE has
been modified to display a decompiled source that is in most cases
very similar to the original source on disk.

VIEW behaves identically as that in F83.  It opens the .SEQ file
in which a word is defined and displays 16 lines of source code
from the beginning of the definition.  You can use the ED command
to enter the editor and exploring the source code before or after
this definition.  Alternatively, you can use the B or N commands
to examine the source one screen at a time without leaving F-PC
even temporarily.

HELP is a new function added in F-PC, which opens the companion
.HLP file to the .SEQ file in which a word is defined and displays
the help messages associated with the word.  It assumes that the
help file exists; otherwise, a file error message will be
displayed.

WORDS behaves identically as WORDS in F83 when used normally to
display the names of definitions in the CONTEXT vocabulary.  It is
enhanced in F-PC such that if the string following it is not a
valid name in the CONTEXT vocabulary, it will use the string as a
substring pattern and prints the names of all definitions in all
vocabularies, whose name contains the substring.  The special
string '*.*' given after WORDS causes all words in all
vocabularies to be displayed.



5.   DATE AND TIME



A complete set of time and date manipulation words has been
provided in F-PC.  They call appropriate DOS service functions to
produce the needed services.  The words for getting and setting
the date and time are as follows:

                GETDATE         ( --- d1 )

Return d1 the 32bit binary date from the operating system.

                SETDATE         ( d1 --- )

Given the binary date d1, set the system clock to that date. Bytes
in d1 are arranged as year/month/day/day-of-week.

                GETTIME         ( --- d1 )

Return d1 with bytes arranged in the order hr/min/sec/100th-sec
from the operating system.

                SETTIME         ( d1 --- )

Given the binary time d1, set the system clock to that time.

                .DATE           ( --- )

Print to the screen, the current date, in the format MM/DD/YY,
where MM is month, DD is day, and YY is year.

                .TIME           ( --- )

Print to the screen, the current time, in the format HH:MM:SS.HR,
where HH is hours, MM is minutes, ss is seconds, and HR is
hundredths of a second.

A special word set is defined in F-PC for measuring elapsed time
for real time experiments and for program characterization.

                TIMER           ( words --- )

TIMER performs the Forth words following on the same command line,
and when they finish execution, TIMER prints the elapsed time
required for their execution.

                TIME-RESET      ( --- )

Reset the accumulated time value in the double variable STIME to
zero, in effect resetting the current elapsed time to zero.  This
word is used at the beginning of a sequence of operations you want
to time.  The word .ELAPSED is used at the end of the operations
to print the elapsed time since the last TIME-RESET.

                .ELAPSED        ( --- )

Print the elapsed time since the last TIME-RESET was performed.

                TENTHS          ( tenths_ofa_second --- )
                SECONDS         ( seconds --- )
                MINUTES         ( minutes --- )
                HOURS           ( hours --- )

Time delay words use the system time function to obtain very
accurate time delays.  Background processing continues, as pause
is called in the wait loop.  Another deferred word, PAUSE-FUNC, is
also in the loop, which can be re deferred to perform any function
you want done while the delay is occurring.



6.   COMMENTS



All comment words in F83, like (, .(, (S, \, \S are preserved and
they behave identically in F-PC.  However, a file in F-PC is similar
to a block in F83 and \S stops the compilation of the rest of the
file.  To accommodate documentation which spans over many lines,
additional comment words are defined in F-PC.


Multiple line comment in F-PC starts with COMMENT: and terminates
at COMMEMT; .  It looks like:

                COMMENT:
                <text>
                <more text>
                ...
                <even more text>
                COMMENT;

To print multiple line comments during compiling,

                .COMMENT:        ( lines_of_text --- )
                ...
                COMMENT;

Starts a group of lines, that are to be printed to the terminal,
until a terminating "COMMENT;" is found.



7.  SCREEN CONTROL WORDS IN F-PC



F-PC allows you to control the CRT screen to generate very fancy
text displays.  Most of these screen control words call DOS video
service to change the character attributes on characters emitted
to the screen.

                FAST            ( --- )

Select the Fast screen output routines that are very hardware
dependant.  Much faster than BDOS, but requires VERY compatible
hardware.

                SLOW            ( --- )

Select the SLOW screen output routines, these routines use BDOS
for screen output, and are less hardware dependant than FAST.

                >UL             ( --- )         underline
                >REV            ( --- )         reverse
                >BOLD           ( --- )         bold
                >BOLDUL         ( --- )         bold underline
                >BOLDBLNK       ( --- )         bold blink
                >REVBLNK        ( --- )         reverse blink
                >NORM           ( --- )         normal video

Select the various types of attributes available on the monochrome
monitor.

COLOR support has been added.  F-PC as delivered is configured for
Monochrome, but will work on a color monitor. The INSTALL process
will automatically install color support if a color board is being
used during installation.

                >FG             ( n1 --- )      foreground
                >BG             ( n1 --- )      background

Words from the COLOR.SEQ file that allow setting the foreground
and background colors on a color monitor:

                >ATTRIB1        ( --- )
                >ATTRIB2        ( --- )
                >ATTRIB3        ( --- )
                >ATTRIB4        ( --- )

Deferred words to allow selection of the various display
attributes for the current display board.  They default to the
following attributes for Monochrome and Color.


                                MONOCHROME          COLOR
                  word                          bgrnd   fgrnd
                ---------------------------------------------
                >ATTRIB1        UNDERLINE       BLUE    GREEN
                >ATTRIB2        BOLD UNDERLINE  RED     WHITE
                >ATTRIB3        BOLD            BLUE    WHITE
                >ATTRIB4        REVERSE         RED     WHITE

These values can be changed by changing either COLOR.SEQ, or
MONOCROM.SEQ and re-installing the system with INSTALL.BAT.

                SAVESCR         ( --- )         save screen
                RESTSCR         ( --- )         restore screen

These words give you the ability to save the screen contents and
later restore the screen to its original appearance in a simple
way. SAVESCR may be used and nested up to three times before
RESTSCR needs to be done. That is, three screens can be saved and
sequentially restored.



8.   COMPILATION CONTROL WORDS



To load a source file, the most convenient way is to use the
command FLOAD:

                FLOAD <file_name> <enter>

will open the file and compile the source code start at the
beginning.  After the file is compiled, FLOAD closes the file so
that other files can be loaded.

If a file is openned by the editor,

                OK <enter>

compile the currently open file, starting at the beginning, and
continuing through the end of the file or until an error is
encountered.

                <line_number> LOAD <enter>

Start loading the current file starting at the <line_number>
specified.  Loads through the end of the file or until an error is
encountered.

A tool of the type used in F83X has been added, called ?NEEDS.
This word when followed by a filename will conditionally load the
specified file if the file has not already been loaded. Be sure to
include the filename extension. Another word ?UNWANTED, when
followed by a filename, aborts with an error if the Unwanted file
has already been loaded.

The word #IF has been added, which accepts a boolean flag, and
determines if the lines following #IF are loaded up until the
#ENDIF. A TRUE flag causes the lines to be loaded. A FALSE flag
causes the lines to be skipped.

                TRUE #IF

                        .( This message will be printed.)

                #ENDIF



9.   PRINTING SOURCE FILES IN F-PC.



Files can of course be printed while in the editor, but you can
also print files from the Forth command line as follows:

                OPEN <filename> <enter>         open a file
                LISTING <enter>                 print the file

The print format is the same as the default format for the editor.
Another command which combines the two commands above is as
follows:

                FPRINT <filespec> <enter>

Literally opens the file and performs a LISTING.  Wildcard
characters can be used in the file specification so that many
files are printed with a single FPRINT command.

                INDEX <filespec> <enter>

behaves similarly to FPRINT.  However, it prints only the first
line of each file specified.



10.   GLOBAL SEARCH



One of the neat additions to F-PC is EDITALL.  EDITALL is used as
follows:

        EDITALL <string> <filespecs>... <enter>

All filespecs are searched for string, if string is found, the the
editor is entered on that line of the file, ready for you to
perform an edit or replace on the string. Only the first occurance
of string is located, so repeated Alt-F6 commands can locate
additional occurances of string in the file.  Shift-F8 Replace all
can also be used while in a file to replace all occurances of
string with another string.  When you are done editing, press ESC,
to terminate edit, and the search will continue through the
filespecs specified for additional occurances of string, until all
files have been found that contain string.  This has been very
valuble to me in maintaining the system, and making global changes
to all occurances of a Forth word name.

FLOOK is another interesting addition to F-PC.  It performs
similarly to EDITALL in searching a word through many files, but
just displays the file and line number of all occurances found.